﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Using the classes</title>
  <keywords>
    <keyword translate="true">Data</keyword>
    <keyword translate="true">Data handling</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Using the classes</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This part of the documentation shows some of the possible scenarios using the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> class.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">First object</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This example shows how to create a basic object that can be used as a “normal” CLR object:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// SimpleObject class which fully supports serialization, </text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// property changed notifications, backwards compatibility and error checking.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">[Serializable]</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">class</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> SimpleObject : ModelBase&lt;SimpleObject&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Initializes a new object from scratch.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> SimpleObject()</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160;: </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">base</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">() { }</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Initializes a new object based on serialization info.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> SimpleObject(SerializationInfo info, StreamingContext context)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160;: </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">base</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(info, context) { }</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Gets or sets the simple property.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> SimpleProperty</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160;get { </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">return</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> GetValue(SimplePropertyProperty); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160;set { SetValue(SimplePropertyProperty, value); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Register the property so it is known in the class.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">readonly</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> PropertyData SimplePropertyProperty = RegisterProperty(&quot;SimpleProperty&quot;, </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">), </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">.Empty);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Serialization</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This example shows how to use the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_Data_SavableDataObjectBase`1_Save_1_6c2dff68" styleclass="Normal" translate="true">Save</link><text styleclass="Normal" translate="true"> and </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_Data_DataObjectBase_Load``1_1_5629a451" styleclass="Normal" translate="true">Load</link><text styleclass="Normal" translate="true"> methods to serialize/deserialize objects to/from disk. The object itself can also directly serialize/deserialize into memory, but this is not shown in the example.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To save an object, call the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_Data_SavableDataObjectBase`1_Save_1_6c2dff68" styleclass="Normal" translate="true">Save</link><text styleclass="Normal" translate="true"> method on the object itself:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">myObject.Save(&quot;MyFile.dob&quot;,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">SerializationMode.Binary);</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To load an object, call the static </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_Data_DataObjectBase_Load``1_1_5629a451" styleclass="Normal" translate="true">Load</link><text styleclass="Normal" translate="true"> method on the class to load:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">SerializableObject</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">myObject</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">SerializableObject.Load(&quot;MyFile.dob&quot;,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">SerializationMode.Binary);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Backwards compatibility for binary serialization</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This example shows how an “old” (standard .NET) data class that uses custom binary serialization can easily be converted to a </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> to use the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> even for all your existing classes.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Declare a new </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> class (remember the ‘dataobject’ code snippet). If the new class is in a new assembly, or has a new name or namespace, use the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Runtime_Serialization_RedirectTypeAttribute" styleclass="Normal" translate="true">RedirectType</link><text styleclass="Normal" translate="true"> attribute to let the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> know that when it finds the old type, it should deserialize that type into the new type.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Then, by default, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Data_ModelBase" styleclass="Normal" translate="true">ModelBase</link><text styleclass="Normal" translate="true"> class will try to deserialize the old object. If it fails to do so, it will fall back on the default values provided by the property declarations. However, it is also possible to override the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_Data_DataObjectBase_GetDataFromSerializationInfo_1_24c9fed9" styleclass="Normal" translate="true">GetDataFromSerializationInfo</link><text styleclass="Normal" translate="true"> method:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Retrieves the actual data from the serialization info.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;remarks&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// This method should only be implemented if backwards compatibility should be implemented for</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// a class that did not previously implement the ModelBase class.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/remarks&gt;</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">protected</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">override</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">void</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> GetDataFromSerializationInfo(SerializationInfo info)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// Check if deserialization succeeded</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">if</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> (DeserializationSucceeded)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">return</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// Deserialization did not succeed for any reason, so retrieve the values manually</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// Luckily there is a helper class (SerializationHelper) </text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// that eases the deserialization of &quot;old&quot; style objects</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;FirstName = SerializationHelper.GetString(info, &quot;FirstName&quot;, FirstNameProperty.GetDefaultValue());</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;LastName = SerializationHelper.GetString(info, &quot;LastName&quot;, LastNameProperty.GetDefaultValue());</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Revert and apply</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">This example shows how to create a state for an object. This is extremely useful when an object is used in an edit mode. Just before the window is shown, a new state is created. Then, when the user clicks the OK button, the new state is applied. When the user clicks the Cancel button, the changes are cleared by reverting to the state created when the window just opened.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To create a state, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">myObject.BeginEdit();</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To apply all changes made to the object since the last state, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">myObject.EndEdit();</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To revert all changes made to the object since the last state, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">myObject.CancelEdit();</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text></para>
  </body>
</topic>
